home *** CD-ROM | disk | FTP | other *** search
/ The 640 MEG Shareware Studio 2 / The 640 Meg Shareware Studio CD-ROM Volume II (Data Express)(1993).ISO / clang / dtk_demo.zip / CHAP4.TXT < prev    next >
Text File  |  1991-09-12  |  13KB  |  471 lines
  1. Chapter 4:  The Demonstration Programs
  2.  
  3.  
  4. There are nineteen demonstration programs provided in source and
  5. executable form, and an additional demonstration program provided
  6. only as an executable file.  Below is given, for each program, a
  7. brief description of what it does, its usage display and a list of
  8. the Dolphin functions used in the program.  The usage display is
  9. the reminder of the syntax which is displayed when the program name
  10. is entered at the DOS prompt without any command line parameters. 
  11. Some programs do not have usage displays.
  12.  
  13. Certain details of the use of many of the Dolphin functions in
  14. these demonstration programs are explained in the corresponding
  15. parts of Chapter 3.  Some date programs omit the "19" when display-
  16. ing dates in this century.  The display format is selectable (see
  17. the DATEFORM program).
  18.  
  19.  
  20. (a) CALCONV
  21.  
  22. Description:
  23.  
  24. This program exercises the basic date conversion functions, namely,
  25. those which convert between a calendrical date and a Julian day
  26. number. (Julian day numbers are explained in Chapter 3, Section 1.) 
  27. The program is three programs in one.  The first converts a date to
  28. a Julian day number (and also shows the day of the week for that
  29. date).  The second converts a Julian day number back to a date
  30. (with day-of-week).  The third takes two dates, converts them to
  31. Julian day numbers and displays the difference plus one, i.e. the
  32. number of days between those dates and including them.
  33.  
  34. Note that dates in this century must be entered as: month day
  35. 19year.  If you enter 12 31 92 then the program will assume you
  36. mean not a date in the 20th Century but rather a date in the 1st
  37. Century.
  38.  
  39. Usage display:
  40.  
  41. This program provides three calendrical conversions:
  42. 1.  For date to day-of-week and Julian day number use CALCONV
  43. month day year. 
  44. 2.  For Julian day number to date and day-of-week use CALCONV jdn. 
  45. 3.  For days between dates use CALCONV m1 d1 y1 m2 d2 y2.
  46. The number of parameters (3, 1 or 6) determines the conversion per-
  47. formed. All dates are in the Gregorian calendar (or in the proleptic
  48. Gregorian calendar if prior to October 15, 1592 (Gregorian)).
  49.  
  50. Dolphin functions used:
  51.  
  52.     date_to_jdn()
  53.     date_to_str()
  54.     day_name()
  55.     day_of_week()
  56.     days_in_date_range()
  57.     jdn_to_date()
  58.     set_date_format_default()
  59.     sltoa_commas()
  60.  
  61.  
  62. (b) DATEFORM
  63.  
  64. Description:
  65.  
  66. This program takes a date and demonstrates the many ways in which
  67. a date can be formatted.  The combinations of different values in
  68. the Date_format structure, which is used to control the date
  69. display, allow for hundreds of different date display formats.
  70.  
  71. Usage display:
  72.  
  73. Use DATEFORM month day year
  74.  
  75. Dolphin functions used:
  76.  
  77.     date_to_str()
  78.     date_valid()
  79.     output_redirected()
  80.     pad_on_right()
  81.     set_date_format_default()
  82.     string()
  83.  
  84.  
  85. (c) NWEEKDAY
  86.  
  87. Description:
  88.  
  89. This program demonstrates the use of some date functions.  It is
  90. used to calculate the date of a particular day of the week in a
  91. given month of a given year.
  92.  
  93. Usage display:
  94.  
  95. Use: NWEEKDAY n day_name month year
  96. This gives the date of the nth Friday or whatever
  97. for the specified month and year in the Gregorian calendar. The day
  98. name can be abbreviated, e.g. NWEEKDAY 3 Fri 12 2012.
  99.  
  100. Dolphin functions used:
  101.  
  102.     capitalize()
  103.     date_to_str()
  104.     date_valid()
  105.     day_name()
  106.     day_of_week()
  107.     ordinal_suffix()
  108.     set_date_format_default()
  109.  
  110.  
  111. (d) TIMEFORM
  112.  
  113. Description:
  114.  
  115. This program takes a time and demonstrates the ways in which a time
  116. can be formatted.  The combinations of different values in the
  117. Time_format structure, which is used to control the time display,
  118. allow for at least 27 different time display formats.
  119.  
  120. Usage display:
  121.  
  122. Use TIMEFORM hour minute second hsecond
  123.  
  124. Dolphin functions used:
  125.  
  126.     pad_on_left()
  127.     set_time_format_default()
  128.     time_to_str()
  129.     time_valid()
  130.  
  131.  
  132. (e) DSKPARAM
  133.  
  134. Description:
  135.  
  136. This program displays normally inaccessible information about the
  137. disk in each of the available drives.  The data displayed is: drive
  138. number, device driver unit number, bytes per sector, sectors per
  139. cluster, shift factor, number of reserved boot sectors, number of
  140. FATs, number of root directory entries, offset to first data
  141. sector, number of clusters, sectors per FAT, offset to first root
  142. directory sector, device driver address and the media descriptor
  143. byte.  Further details are given in Chapter 3, Section 4.
  144.  
  145. Usage display: none
  146.  
  147. Dolphin functions used:
  148.  
  149.     bios_disk_present()
  150.     get_drive_parameter_block()
  151.     output_redirected()
  152. (f) CURRDIR
  153.  
  154. Description:
  155.  
  156. This program displays the current subdirectories on all drives, and
  157. then randomly changes the current directory to a subdirectory on
  158. some drive.
  159.  
  160. Usage display: none
  161.  
  162. Dolphin functions used:
  163.  
  164.     bios_disk_present()
  165.     get_directory()
  166.     high_drive()
  167.     last_drive_used()
  168.     num_floppy_drives()
  169.     set_directory()
  170.     strrchr_n()
  171.     time_elapsed_this_year()
  172.  
  173.  
  174. (g) SPLIT_P
  175.  
  176. Description:
  177.  
  178. This program demonstrates the directory functions to normalize a
  179. subdirectory path which is input by a user, and to split that path
  180. into its components and to recombine them.  When run it awaits the
  181. entry of a path.  This can include .., as in:
  182.  
  183.                      ..\..\ABC\DEF\..\GHI
  184.  
  185. The path is checked for validity and for existence.
  186.  
  187. Usage display: none
  188.  
  189. Dolphin functions used:
  190.  
  191.     gets_n()
  192.     make_path()
  193.     normalize_path()
  194.     split_path()
  195.     trim()
  196.  
  197.  
  198. (h) DIR_ATTR
  199.  
  200. This program displays the files in a given subdirectory which
  201. satisfy a given file specification together with their file
  202. attributes.  As explained in 3.6(a), the attribute specification is
  203. a string of the form [str1][!str2] which consists of one or more of
  204. R, H, S, V, D and A, which are interpreted as: R = read only, 
  205. H = hidden, S = system, V = volume label, D = directory and 
  206. A = archive.  The string str1!str2 means: having one or more of the
  207. attributes in str1 and none of the attributes in str2; e.g. D!H
  208. means all directories which are not hidden and !HSVD means all
  209. files except those which are hidden, system, volume labels or
  210. directories.  If the attribute specification is the empty string or
  211. is the null pointer NULL then all non-hidden files (other than
  212. directories and any volume name) are assumed; this is equivalent to
  213. attribute specification !HVD.
  214.  
  215. Description:
  216.  
  217. Usage display:
  218.  
  219. Use: DIR_ATTR file_spec [attribute_spec]
  220. file attributes: RHSVDA, ! = not, e.g. DIR_ATTR K*.* AS!R
  221.  
  222. Dolphin functions used:
  223.  
  224.     num_matching_files()
  225.     output_redirected()
  226.     read_directory()
  227.  
  228.  
  229. (i) SETFDATE
  230.  
  231. Description:
  232.  
  233. This is a small utility for setting the date and time stamp on a
  234. file. It accepts pathnames and wildcards, so it is possible, e.g.
  235. to use: SETFDATE \XYZ\*.TXT 31-12-1992 12:00.  This is similar to
  236. the TOUCH utility provided by some vendors.
  237.  
  238. Important:  Do not change the dates of the executable files on the
  239. demonstration disk if you want VALIDATE.EXE to report that they
  240. have the correct date.
  241.  
  242. Usage display:
  243.  
  244. Use: SETFDATE file_spec [month-day-year] [hour:minute]
  245.  
  246. Dolphin functions used:
  247.  
  248.     date_to_str()
  249.     date_valid()
  250.     get_system_date()
  251.     get_system_time()
  252.     normalize_path()
  253.     set_date_format_default()
  254.     set_file_date_time()
  255.     set_time_format_default()
  256.     time_to_str()
  257.     time_valid()
  258.  
  259.  
  260. (j) COMPARE
  261.  
  262. Description:
  263.  
  264. This is a utility to compare files.  It differs from the COMP
  265. utility provided with DOS in that it accepts wildcards.  Thus one
  266. may enter: COMPARE \ABC\*.* \UVW\XYZ\*.* to compare all files in
  267. \ABC with files of the same name in \UVW\XYZ.
  268.  
  269. Usage display:
  270.  
  271. Use: COMPARE file_1 file_2
  272.      wildcards OK (e.g. COMPARE *.TXT *.DEC)
  273.  
  274. Dolphin functions used:
  275.  
  276.     get_input_output_files()
  277.     make_path()
  278.     split_path()
  279.  
  280.  
  281. (k) NUMLINES
  282.  
  283. Description:
  284.  
  285. This counts the number of lines in a textfile, distinguishing
  286. between blank and non-blank lines.
  287.  
  288. Usage display:
  289.  
  290. Use: NUMLINES filename
  291.  
  292. Dolphin functions used:
  293.  
  294.     num_lines_in_file()
  295.  
  296.  
  297. (l) PR_SPOOL
  298.  
  299. Description:
  300.  
  301. This program demonstrates the use of the interface provided in this
  302. library to the print spooler PRINT.COM (or PRINT.EXE).  When run it
  303. checks whether the print spooler is installed, and if not asks
  304. whether to install it.  A file for printing may be specified at the
  305. command line (e.g. PR_SPOOL FILE.TXT) but wildcards in the file
  306. specification are not allowed (this is left as an exercise for the
  307. reader).  The program maintains the following menu:
  308.  
  309. ... files in print queue: ...
  310.  
  311. S Submit a file    C Cancel a file (wildcards OK)   A Cancel all
  312. files H Hold the queue   E End the hold   R Redisplay queue   Q
  313. Quit   -->
  314.  
  315. The source code in PR_SPOOL.C shows how the user's selection is
  316. translated into calls to the print spooler.
  317.  
  318. Usage display: none
  319.  
  320. Dolphin functions used:
  321.  
  322.     char_at()
  323.     gets_n()
  324.     print_com_end_hold()
  325.     print_com_cancel_all()
  326.     print_com_cancel_file()
  327.     print_com_hold()
  328.     print_com_install()
  329.     print_com_status()
  330.     print_com_submit_file()
  331.     trim()
  332.  
  333.  
  334. (m) ALL_DRVS
  335.  
  336. Description:
  337.  
  338. This provides information on all physical floppy drives and hard
  339. drives present, showing numbers of tracks, etc.
  340.  
  341. Usage display: none
  342.  
  343. Dolphin functions used:
  344.  
  345.     drive_type()
  346.     num_floppy_drives()
  347.     num_hard_drives()
  348.  
  349.  
  350. (n) FINAL
  351.  
  352. Description:
  353.  
  354. This copies a string from its place in the the near heap (in the
  355. default data segment) to a place in the far heap (outside of the
  356. default data segment) and displays the final character of each
  357. occurrence of the string.
  358.  
  359. Usage display: none
  360.  
  361. Dolphin functions used:
  362.  
  363.     final_char()
  364.     final_null()
  365.     strcpy_f()
  366.  
  367.  
  368. (o)  TIMER
  369.  
  370. Description:
  371.  
  372. This program times keypresses.  The time is measured either in
  373. clock ticks or in seconds.  The system clock ticks at the rate of
  374. 18.20651245 ticks per second.
  375.  
  376. Usage display: none
  377.  
  378. Dolphin functions used:
  379.  
  380.      time_elapsed()
  381.  
  382.  
  383. (p) DISKTYPE
  384.  
  385. Description: This program determines the type of disk in a
  386. specified drive.  It distinguishes among different floppy disk
  387. types.  Anything which is not a floppy disk is reported as a fixed
  388. disk.  This may be either a hard disk or a RAM disk.
  389.  
  390. Usage display: 
  391.  
  392. Use: DISKTYPE drive_letter
  393.  
  394. Dolphin functions used:
  395.  
  396.      get_disk_free()
  397.      disk_type()
  398.  
  399.  
  400. (q) MAKE&DEL
  401.  
  402. Description: This program makes names for 26 new files (i.e. names
  403. which are not already names of files in the current subdirectory)
  404. and creates them.  It then deletes all files created.
  405.  
  406. Usage display: none
  407.  
  408. Dolphin functions used:
  409.  
  410.      make_new_file_name()
  411.      delete_files()
  412.  
  413.  
  414. (r) SAVEVALS
  415.  
  416. Description: This program displays the current values of a string
  417. variable x and an integer variable y then allows them to be
  418. changed.  The new values are saved in SAVEVALS.EXE and displayed
  419. the next time the program is run.
  420.  
  421. Usage display: none
  422.  
  423. Dolphin functions used:
  424.  
  425.      gets_n()
  426.      trim()
  427.      save_values_in_exe()
  428.  
  429.  
  430. (s) FILETYPE
  431.  
  432. Description: This program displays the file types of the file(s)
  433. specified on the command line; wildcards are permitted.
  434.  
  435. Usage display: 
  436.  
  437. Use: FILETYPE file_spec
  438.  
  439. Dolphin functions used:
  440.  
  441.      file_type()
  442.      get_input_output_files()
  443.      make_path()
  444.      split_path()
  445.  
  446.  
  447. (t) MCDEMO
  448.  
  449. Description:
  450.  
  451. This is a self-running demonstration of Dolphin Software's Mayan
  452. Calendrics program.  It uses the date functions from this library
  453. as the basis for a comprehensive calendrical conversion program.
  454.  
  455. The program converts dates in the Maya calendar to and from Western
  456. dates.  Maya dates may be either dates in the sacred and civil
  457. calendars (the so-called tzolkin/haab dates, e.g. 13 Imix 19 Kayab)
  458. or long count dates (e.g. 9.9.16.0.0).  Western dates may be
  459. expressed in either the Gregorian calendar or the Julian calendar. 
  460. A date expressed in any calendrical system is automatically con-
  461. verted to dates in all the others (and to the Julian day number). 
  462. Arithmetic operations with long count dates are supported.
  463.  
  464. When a tzolkin/haab date is entered the software displays which
  465. year-bearer systems it is consistent with, and allows identifica-
  466. tion of all Western dates within a given range of years which
  467. correspond to that tzolkin/haab date.
  468.  
  469. The source code for this program is not included on the demonstra-
  470. tion disk.
  471.